home *** CD-ROM | disk | FTP | other *** search
/ Best Tools for JAVA / Best Tools for JAVA.iso / JAVA_ALL / IDE / SUBARTIC / SUB_ARCT / INPUT / FOCUS_DI.JAV < prev    next >
Encoding:
Text File  |  1996-10-04  |  12.1 KB  |  359 lines
  1.  
  2. package sub_arctic.input;
  3.  
  4. import sub_arctic.lib.interactor;
  5. import sub_arctic.lib.sub_arctic_error;
  6.  
  7. import java.util.Vector;
  8.  
  9. /**
  10.  * This is the abstract base class for all focus dispatch agents.  It provides
  11.  * infrastructure for maintaining objects in focus sets, notifying objects of
  12.  * entry and exit from the focus set, etc.  This (partial) agent dispatches
  13.  * input under the focusable input protocol.<p>
  14.  *
  15.  * @see sub_arctic.input.focusable
  16.  * @author Scott Hudson
  17.  */
  18. public abstract class focus_dispatch_agent extends dispatch_agent {
  19.  
  20.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  21.  
  22.   /* Default constructor.  This creates an empty focus set to start with. */
  23.   public focus_dispatch_agent() 
  24.     {
  25.       _focus_set = new Vector();
  26.       _user_info_set = new Vector();
  27.     }
  28.  
  29.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  30.  
  31.   /** 
  32.    * Focus set.  This contains focusable objects and maintains all objects
  33.    * that are currently in the focus set for this agent.  This list is 
  34.    * maintained in synch with _user_info_set which contains the user info
  35.    * objects belonging to each object in the focus set.
  36.    */
  37.   protected Vector _focus_set;
  38.  
  39.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  40.  
  41.   /**
  42.    * Each focus object may provide a user info object when it is placed in 
  43.    * the focus set.  This vector maintains the set of those objects 
  44.    * corresponding the interactor objects in the current focus set.  Positions 
  45.    * in this vector correspond directly to positions in _focus_set.  This 
  46.    * vector contains objects of any type.
  47.    */
  48.   protected Vector _user_info_set;
  49.  
  50.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  51.  
  52.   /** Indicate the size of the current focus set. */
  53.   public int focus_set_size() {return _focus_set.size();}
  54.  
  55.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  56.  
  57.   /** 
  58.    * Return the focus object at a given index in the focus set vector. 
  59.    * @param int at_indx the index of the requested object.
  60.    * @returns focusable the object at that index.
  61.    */
  62.   public focusable focus_item(int at_indx) {
  63.     if (at_indx < 0 || at_indx >= _focus_set.size()) {
  64.       throw new sub_arctic_error("Request for focus set item out of range");
  65.     }
  66.     return (focusable)_focus_set.elementAt(at_indx);
  67.   }
  68.  
  69.    //had:
  70.    //* @exception index_bounds if the index is out of range.
  71.  
  72.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  73.  
  74.   /**
  75.    * Retrieve the user info object corresponding to the focusable object at
  76.    * the given index.
  77.    * @param int at_indx the index of the requested object.
  78.    * @returns Object user info for the object at that index.
  79.    */
  80.   protected Object user_info_item(int at_indx) {
  81.     if (at_indx < 0 || at_indx >= _focus_set.size())
  82.       throw new sub_arctic_error("Request for user info set item out of range");
  83.     return _user_info_set.elementAt(at_indx);
  84.   }
  85.  
  86.    //had:
  87.    //* @exception index_bounds if the index is out of range.
  88.  
  89.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  90.  
  91.   /** 
  92.    * This method is called whenever an object enters the focus set.  It 
  93.    * calls focus_set_enter() on the object (as part of the focusable input
  94.    * protocol).  Note: in some subclass agents, the focus_set_enter() call
  95.    * is replaced by a more specific call particular to the protocol managed
  96.    * by that agent. <p>
  97.    *
  98.    * @param focusable obj       the object entering the focus set.
  99.    * @param event     evt       the event that "caused" the entry.
  100.    * @param Object    user_info the user info associated with that object.
  101.    */
  102.   protected void inform_focus_enter(
  103.     focusable obj, 
  104.     event     evt, 
  105.     Object    user_info) {
  106.     /* dispatch it */
  107.     obj.focus_set_enter(evt,this,user_info);
  108.   }
  109.  
  110.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  111.  
  112.   /** 
  113.    * This method is called whenever an object exits the focus set.  It 
  114.    * calls focus_set_exit() on the object (as part of the focusable input
  115.    * protocol).  Note: in some subclass agents, the focus_set_exit() call
  116.    * is replaced by a more specific call particular to the protocol managed
  117.    * by that agent. <p>
  118.    *
  119.    * @param focusable obj       the object exiting the focus set.
  120.    * @param event     evt       the event that "caused" the exit.
  121.    * @param Object    user_info the user info associated with that object.
  122.    */
  123.   protected void inform_focus_exit(
  124.     focusable obj, 
  125.     event     evt, 
  126.     Object    user_info) {
  127.     /* dispatch it */
  128.     obj.focus_set_exit(evt,this,user_info);
  129.   }
  130.  
  131.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  132.  
  133.   /** Do subclass specific test to see if the given object is eligible to
  134.    *  go in the focus set.  Typically we would test that the object implements
  135.    *  the interface that defines the input dispatch protocol in question.
  136.    *  Here in the superclass we let anything in.<p>
  137.    *
  138.    * @param focusable candidate_obj object we are accepting or rejecting
  139.    * @return boolean indicating if the object is suitable for inclusion in the
  140.    *                 focus set.
  141.    */
  142.   public boolean allowable_focus(focusable candidate_obj) {
  143.     return true;
  144.   }
  145.  
  146.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  147.  
  148.   /**
  149.    * Replace the focus set of this agent with the given object.  This provides
  150.    * a causal event and an uninterpreted object that will be passed back to
  151.    * the focus object whenever input is delivered to it by this agent.<p>
  152.    *
  153.    * @param focusable to_obj    the object going in the focus set.
  154.    * @param event     evt       the event that "caused" this focus.
  155.    * @param Object    user_info the uninterpreted information that we will pass
  156.    *                            back to the object whenever it gets input from
  157.    *                            this agent.
  158.    */
  159.   public void set_focus_to(focusable to_obj, event evt, Object user_info) {
  160.     int       i;
  161.     focusable remove_obj;
  162.     Object    remove_info;
  163.     boolean   already_focus = false;
  164.     
  165.     /* make sure its ok to add */
  166.     if (!allowable_focus(to_obj))
  167.       throw new sub_arctic_error("Attempt to add an ineligible object to the focus set");
  168.     
  169.       /* if they set to a null focus, treat that as a clear */
  170.       if (to_obj == null)
  171.     {
  172.       clear_focus(evt);
  173.       return;
  174.     }
  175.  
  176.       /* inform all the old focus objects that they have lost focus */
  177.       for (i = 0; i < _focus_set.size(); i++)
  178.     {
  179.       remove_obj = (focusable)_focus_set.elementAt(i);
  180.       remove_info = _user_info_set.elementAt(i);
  181.  
  182.       /* but don't inform the object we are about to put in... */
  183.       if (to_obj !=  remove_obj)
  184.         inform_focus_exit(remove_obj,evt,remove_info);
  185.       else
  186.         already_focus = true;
  187.     }
  188.  
  189.       /* dump the old set and start over */
  190.       _focus_set = new Vector();
  191.       _focus_set.addElement(to_obj);
  192.       _user_info_set = new Vector();
  193.       _user_info_set.addElement(user_info);
  194.  
  195.       /* if we are just entering, inform the object */
  196.       if (!already_focus)
  197.     inform_focus_enter(to_obj,evt,user_info);
  198.     }
  199.  
  200.    //had:
  201.    //* @exception bad_value if this object is not suitable for inclusion in this
  202.    //*                      focus set.
  203.  
  204.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  205.  
  206.   /** 
  207.    * Determine if the given object is currently part of the focus set for this
  208.    * agent.<p>
  209.    *
  210.    * @param focusable obj the object we are asking about
  211.    * @return boolean indicating whether the object is in the focus set.
  212.    */
  213.   public boolean is_in_focus(focusable obj)
  214.     {
  215.       int indx;
  216.  
  217.       /* look for the object in the focus set */
  218.       indx = _focus_set.indexOf(obj);
  219.  
  220.       /* -1 indicates not there */
  221.       return indx >= 0;
  222.     }
  223.  
  224.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  225.  
  226.   /**
  227.    * Add an object to the focus set of this agent.  This provides
  228.    * a causal event and an uninterpreted object that will be passed back to
  229.    * the focus object whenever input is delivered to it by this agent.<p>
  230.    *
  231.    * @param focusable to_obj    the object going in the focus set.
  232.    * @param event     evt       the event that "caused" this focus.
  233.    * @param Object    user_info the uninterpreted information that we will pass
  234.    *                            back to the object whenever it gets input from
  235.    *                            this agent.
  236.    */
  237.   public void add_to_focus(focusable new_obj, event evt, Object user_info)
  238.     {
  239.       /* make sure its ok to add */
  240.       if (!allowable_focus(new_obj))
  241.     throw new sub_arctic_error(
  242.       "Attempt to add an ineligible object to the focus set");
  243.  
  244.       /* don't do anything if we are already in the focus set */
  245.       if (!is_in_focus(new_obj))
  246.     {
  247.       /* add it to the focus set and let it know its been added */ 
  248.       _focus_set.addElement(new_obj);
  249.       _user_info_set.addElement(user_info);
  250.       inform_focus_enter(new_obj, evt, user_info);
  251.     }
  252.     }
  253.  
  254.    //had:
  255.    //* @exception bad_value if this object is not suitable for inclusion in this
  256.    //*                      focus set.
  257.    //* @exception general
  258.  
  259.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  260.  
  261.   /** 
  262.    * Remove the given object from the focus set of this agent.
  263.    * @param focusable obj the object to be removed.
  264.    * @param event     evt the event that "caused" this removal.
  265.    */
  266.   public void remove_from_focus(focusable obj, event evt)
  267.     {
  268.       int indx;
  269.       Object user_info;
  270.  
  271.       /* find the object */
  272.       indx = _focus_set.indexOf(obj);
  273.  
  274.       /* if its not there, throw an exception */
  275.       if (indx < 0) 
  276.     throw new sub_arctic_error(
  277.       "Attempt to remove focus from an object not in the focus set");
  278.  
  279.       /* otherwise remove it and let it know */
  280.       _focus_set.removeElementAt(indx);
  281.       user_info = _user_info_set.elementAt(indx);
  282.       _user_info_set.removeElementAt(indx);
  283.       inform_focus_exit(obj, evt, user_info);
  284.     }
  285.  
  286.    //had:
  287.    //* @exception bad_value if this object is not not in the focus set.
  288.    //* @exception general
  289.  
  290.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  291.  
  292.   /** 
  293.    * Clear the focus set of this agent to empty.
  294.    * @param event evt the event that "caused" this.
  295.    */
  296.   public void clear_focus(event evt) 
  297. {
  298.       int       i;
  299.       focusable remove_obj;
  300.       Object    remove_info;
  301.  
  302.       /* inform all the old focus objects that they have lost focus */
  303.       for (i = 0; i < _focus_set.size(); i++)
  304.     {
  305.       remove_obj = (focusable)_focus_set.elementAt(i);
  306.       remove_info = _user_info_set.elementAt(i);
  307.       inform_focus_exit(remove_obj,evt,remove_info);
  308.     }
  309.  
  310.       /* dump the old set and start over */
  311.       _focus_set = new Vector();
  312.     }
  313.  
  314.    //has:
  315.    //* @exception general
  316.  
  317.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  318.  
  319.   /** 
  320.    * Attempt to dispatch an event to an object or set of objects via this 
  321.    * agent.  The event is passed in all cases.  In our case (for focus agents),
  322.    * the remaining parameters are ignored as we store the user_info and 
  323.    * object to dispatch to internally, and are not passed the same event
  324.    * more than once.  This method is overridden by each subclass to do its
  325.    * specific work. <p>
  326.    *
  327.    * @param event      evt       the event to be dispatched.
  328.    * @param Object     user_info ignored.
  329.    * @param interactor to_obj    ignored.
  330.    * @param int        seq_num   ignored.
  331.    */
  332.   public abstract boolean dispatch_event(
  333.     event      evt, 
  334.     Object     user_info,
  335.     interactor to_obj, 
  336.     int        seq_num) ;
  337.  
  338.    //had:
  339.    //* @exception general
  340.  
  341.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  342. }
  343. /*=========================== COPYRIGHT NOTICE ===========================
  344.  
  345. This file is part of the subArctic user interface toolkit.
  346.  
  347. Copyright (c) 1996 Scott Hudson and Ian Smith
  348. All rights reserved.
  349.  
  350. The subArctic system is freely available for most uses under the terms
  351. and conditions described in 
  352.   http://www.cc.gatech.edu/gvu/ui/sub_arctic/sub_arctic/doc/usage.html 
  353. and appearing in full in the lib/interactor.java source file.
  354.  
  355. The current release and additional information about this software can be 
  356. found starting at: http://www.cc.gatech.edu/gvu/ui/sub_arctic/
  357.  
  358. ========================================================================*/
  359.